Bulk Sending Engine

1. Introduction

2. Project Structure

3. Core Components

4. Architecture Overview

5. Detailed Component Analysis

6. Dependency Analysis

7. Performance Considerations

8. Troubleshooting Guide

9. Conclusion

This document explains the bulk message sending engine implemented in the desktop application. It covers the end-to-end workflow for sending WhatsApp messages and emails in bulk, including contact iteration, message personalization, rate limiting, delivery confirmation, progress monitoring, and error handling. It also provides performance optimization techniques and best practices for large-scale campaigns.

The application is organized as a cross-platform desktop app with:

• Electron main process orchestrating IPC handlers and integrations

• React frontend for user controls and progress display

• Python backend utilities for contact processing and validation

• Local development server and prototype utilities

Diagram sources

• BulkMailer.jsx

• WhatsAppForm.jsx

• main.js

• gmail-handler.js

• smtp-handler.js

• app.py

• extract_contacts.py

• validate_number.py

Section sources

• README.md

• package.json

• Electron main process manages WhatsApp client lifecycle, handles IPC events, and coordinates email sending via Gmail API and SMTP.

• React components provide user controls for connecting to WhatsApp, importing contacts, composing messages, and monitoring progress.

• Python backend exposes REST endpoints for contact import and parsing, and standalone utilities for contact extraction and phone number validation.

• Pyodide runtime enables running Python logic directly in the renderer process for manual number parsing.

Key responsibilities:

• Contact ingestion and normalization

• Message personalization

• Rate limiting and throttling

• Delivery confirmation and status tracking

• Error handling and retries

Section sources

• BulkMailer.jsx

• main.js

• gmail-handler.js

• smtp-handler.js

• app.py

• extract_contacts.py

• validate_number.py

• pyodide.js

The bulk sending engine integrates three channels:

• WhatsApp Web: QR-based authentication, per-contact registration checks, and per-message delays.

• Gmail API: OAuth2-based sending with per-email delays and progress updates.

• SMTP: Transport-based sending with per-email delays and progress updates.

Diagram sources

• main.js

• gmail-handler.js

• smtp-handler.js

WhatsApp Bulk Sending#

Workflow:

• Initialize WhatsApp client with local authentication strategy.

• Display QR code for user authentication.

• After authentication, iterate over contacts:

  • Construct chat ID from phone number.

  • Check if the number is registered on WhatsApp.

  • Personalize message using {{name}} placeholder.

  • Send message with a fixed delay between attempts.

• Report completion metrics (sent vs failed).

Diagram sources

• main.js

• main.js

• WhatsAppForm.jsx

Key implementation details:

• Personalization: Replace {{name}} with contact name or default value.

• Registration check: Uses isRegisteredUser(chatId) to avoid sending to unregistered numbers.

• Delays: Fixed delays between attempts to reduce rate limits and detection risk.

• Status reporting: Real-time updates via IPC channels for UI rendering.

Section sources

• main.js

• WhatsAppForm.jsx

Email Bulk Sending (Gmail API)#

Workflow:

• Authenticate via OAuth2 and persist tokens.

• For each recipient:

  • Prepare email payload.

  • Send via Gmail API.

  • Emit progress updates.

  • Apply configurable delay between sends.

Diagram sources

• gmail-handler.js

• BulkMailer.jsx

Key implementation details:

• OAuth2 flow: Generates auth URL, captures authorization code, exchanges for tokens.

• Token persistence: Stores tokens securely for reuse.

• Progress tracking: Emits structured progress events with current/total and per-recipient status.

• Delay-based rate limiting: Applies delay between sends to avoid throttling.

Section sources

• gmail-handler.js

• gmail-handler.js

• BulkMailer.jsx

Email Bulk Sending (SMTP)#

Workflow:

• Validate SMTP configuration.

• Create transport and verify connectivity.

• For each recipient:

  • Build email options (HTML and plain text).

  • Send via SMTP.

  • Emit progress updates.

  • Apply configurable delay between sends.

Diagram sources

• smtp-handler.js

• BulkMailer.jsx

Key implementation details:

• Transport verification: Ensures SMTP server readiness before sending.

• Credential handling: Optional saving of non-secret config (host/port/secure/user).

• Progress tracking: Same event-driven pattern as Gmail API.

• Delay-based rate limiting: Consistent throttling across providers.

Section sources

• smtp-handler.js

• BulkMailer.jsx

Contact Processing and Validation#

The system supports importing contacts from CSV, TXT, and Excel files, and validating/normalizing phone numbers.

Diagram sources

• app.py

• app.py

• extract_contacts.py

• validate_number.py

• pyodide.js

Key implementation details:

• CSV/Excel parsing: Heuristically detects phone and name columns.

• TXT parsing: Splits by separators and extracts likely phone numbers.

• Manual parsing: Uses Pyodide to run Python logic in the renderer for quick number extraction.

• Validation: Enforces digit-only length constraints and optional leading plus sign normalization.

Section sources

• app.py

• app.py

• app.py

• app.py

• extract_contacts.py

• validate_number.py

• pyodide.js

Rate Limiting and Spam Prevention#

• WhatsApp:

  • Fixed delays between sending attempts to registered users and between failures.

  • Registration checks prevent sending to unregistered numbers, reducing bounce-related errors.

• Gmail/SMTP:

  • Configurable delay between emails to avoid throttling and rate limits.

  • Progress events allow users to adjust delay dynamically.

Best practices:

• Start with conservative delays and increase gradually based on provider feedback.

• Monitor delivery failures and reduce batch sizes for problematic domains/providers.

• Respect provider-specific rate limits and quotas.

Section sources

• main.js

• gmail-handler.js

• smtp-handler.js

Delivery Confirmation and Status Tracking#

• WhatsApp:

  • Real-time status updates for QR generation, authentication, and per-contact send results.

  • Completion summary with sent and failed counts.

• Gmail/SMTP:

  • Per-email progress events with current/total counters and per-recipient status.

  • Structured failure details for diagnostics.

Diagram sources

• main.js

• WhatsAppForm.jsx

Section sources

• main.js

• main.js

• gmail-handler.js

• smtp-handler.js

• WhatsAppForm.jsx

Retry Mechanisms and Error Recovery#

• WhatsApp:

  • Attempts to send to registered users only; failures are recorded and retried on subsequent runs.

  • Disconnection handler resets client state and clears cached files.

• Gmail/SMTP:

  • Per-email failure events include error messages; UI can trigger reattempts selectively.

  • Transport verification helps detect misconfiguration early.

Recommendations:

• Implement explicit retry loops for transient failures.

• Persist partial results to resume interrupted campaigns.

• Provide user controls to pause/resume and adjust retry policies.

Section sources

• main.js

• main.js

• gmail-handler.js

• smtp-handler.js

External libraries and services:

• Electron: Desktop runtime and IPC

• whatsapp-web.js: WhatsApp Web integration

• googleapis: Gmail API authentication and sending

• nodemailer: SMTP transport

• qrcode: QR code generation for WhatsApp

• Pyodide: Python runtime in the browser for manual number parsing

Diagram sources

• package.json

• main.js

• gmail-handler.js

• smtp-handler.js

• pyodide.js

Section sources

• package.json

• requirements.txt

• Concurrency control: Limit simultaneous send operations to respect provider rate limits.

• Batch sizing: Reduce batch size for providers with strict quotas.

• Memory management: Clear cached files and reset client state on disconnects.

• Network resilience: Use exponential backoff for retries and circuit breaker patterns.

• UI responsiveness: Offload heavy tasks to background threads and emit frequent progress updates.

[No sources needed since this section provides general guidance]

Common issues and resolutions:

• WhatsApp QR code not loading:

  • Ensure network connectivity and restart the app.

  • Clear cached files and retry initialization.

• Gmail authentication failures:

  • Verify OAuth2 client credentials and ensure Gmail API is enabled.

• SMTP connection issues:

  • Confirm server settings, ports, and TLS configuration.

• Contact import errors:

  • Validate file format and encoding; ensure proper column headers.

Section sources

• README.md

• main.js

The bulk sending engine integrates WhatsApp Web, Gmail API, and SMTP with robust contact processing, personalization, rate limiting, and progress monitoring. By leveraging IPC handlers, structured progress events, and provider-specific safeguards, it supports reliable large-scale campaigns while maintaining user control and transparency.